/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup OHAudio
 * @{
 *
 * @brief 提供音频模块C接口定义。
 *
 * @syscap SystemCapability.Multimedia.Audio.Core
 *
 * @since 12
 * @version 1.0
 */

/**
 * @file native_audio_session_manager.h
 *
 * @brief 声明音频会话管理相关的接口。\n
 *
 * 包含创建音频会话管理器、激活/停用音频会话、检查音频会话是否已激活，以及监听音频会话停用事件。
 *
 * @library libohaudio.so
 * @syscap SystemCapability.Multimedia.Audio.Core
 * @kit AudioKit
 * @include <ohaudio/native_audio_session_manager.h>
 * @since 12
 * @version 1.0
 */

#ifndef NATIVE_AUDIO_SESSION_MANAGER_H
#define NATIVE_AUDIO_SESSION_MANAGER_H

#include "native_audio_common.h"
#include "native_audiostream_base.h"
#include "native_audio_device_base.h"
#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 声明音频会话管理器。\n
 *
 * 用于管理音频会话相关功能。
 *
 * @since 12
 */
typedef struct OH_AudioSessionManager OH_AudioSessionManager;

/**
 * @brief 音频并发模式。
 *
 * @since 12
 */
typedef enum {
    /**
     * @brief 默认使用系统策略。
     */
    CONCURRENCY_DEFAULT = 0,

    /**
     * @brief 和其它正在播放应用进行混音。
     */
    CONCURRENCY_MIX_WITH_OTHERS = 1,

    /**
     * @brief 后来播放应用压低正在播放应用的音量。
     */
    CONCURRENCY_DUCK_OTHERS = 2,

    /**
     * @brief 后来播放应用暂停正在播放应用。
     */
    CONCURRENCY_PAUSE_OTHERS = 3,
} OH_AudioSession_ConcurrencyMode;

/**
 * @brief 音频会话场景。
 *
 * @since 20
 */
typedef enum {
    /**
     * @brief 媒体音频会话场景。
     */
    AUDIO_SESSION_SCENE_MEDIA = 0,

    /**
     * @brief 游戏音频会话场景。
     */
    AUDIO_SESSION_SCENE_GAME = 1,

    /**
     * @brief VoIP语音通话音频会话场景。
     */
    AUDIO_SESSION_SCENE_VOICE_COMMUNICATION = 2,
} OH_AudioSession_Scene;

/**
 * @brief 音频会话状态变更的提示信息。
 *
 * @since 20
 */
typedef enum {
    /**
     * @brief 提示音频会话恢复，应用可主动触发开始渲染等相关操作。
     */
    AUDIO_SESSION_STATE_CHANGE_HINT_RESUME = 0,

    /**
     * @brief 提示音频会话暂停，暂时失去音频焦点。当焦点再次可用时，会收到AUDIO_SESSION_STATE_CHANGE_HINT_RESUME事件。
     */
    AUDIO_SESSION_STATE_CHANGE_HINT_PAUSE = 1,

    /**
     * @brief 提示音频会话在焦点被抢占后停止，彻底失去音频焦点。
     */
    AUDIO_SESSION_STATE_CHANGE_HINT_STOP = 2,

    /**
     * @brief 提示长时间没有音频业务，音频会话将被系统停止，彻底失去音频焦点。
     */
    AUDIO_SESSION_STATE_CHANGE_HINT_TIME_OUT_STOP = 3,

    /**
     * @brief 提示音频会话躲避开始，降低音量播放。
     */
    AUDIO_SESSION_STATE_CHANGE_HINT_DUCK = 4,

    /**
     * @brief 提示音频会话躲避结束，恢复音量播放。
     */
    AUDIO_SESSION_STATE_CHANGE_HINT_UNDUCK = 5,
} OH_AudioSession_StateChangeHint;

/**
 * @brief 输出设备变更后推荐的操作。
 *
 * @since 20
 */
typedef enum {
    /**
     * @brief 推荐继续播放。
     */
    DEVICE_CHANGE_RECOMMEND_TO_CONTINUE = 0,

    /**
     * @brief 推荐停止播放。
     */
    DEVICE_CHANGE_RECOMMEND_TO_STOP = 1,
} OH_AudioSession_OutputDeviceChangeRecommendedAction;

/**
 * @brief 音频会话停用原因。
 *
 * @since 12
 */
typedef enum {
    /**
     * @brief 应用焦点被抢占。
     */
    DEACTIVATED_LOWER_PRIORITY = 0,

    /**
     * @brief 应用停流后超时。
     */
    DEACTIVATED_TIMEOUT = 1,
} OH_AudioSession_DeactivatedReason;

/**
 * @brief 在使用蓝牙或星闪进行录音时，应用程序的设备偏好分类。
 *
 * @since 21
 */
typedef enum {
    /**
     * @brief 不偏好使用蓝牙或星闪连接进行录音。
     */
    PREFERRED_NONE = 0,
 
    /**
     * @brief 更偏好使用蓝牙或星闪录音。
     * 是否使用低延迟或高质量录音取决于系统。
     */
    PREFERRED_DEFAULT = 1,
 
    /**
     * @brief 更偏好使用蓝牙或星闪低延迟模式进行录音。
     */
    PREFERRED_LOW_LATENCY = 2,
 
    /**
     * @brief 更偏好使用蓝牙或星闪高质量模式进行录音。
     */
    PREFERRED_HIGH_QUALITY = 3,
} OH_AudioSession_BluetoothAndNearlinkPreferredRecordCategory;

/**
 * @brief 音频会话策略。
 *
 * @since 12
 */
typedef struct OH_AudioSession_Strategy {
    /**
     * @brief 音频并发模式。
     */
    OH_AudioSession_ConcurrencyMode concurrencyMode;
} OH_AudioSession_Strategy;

/**
 * @brief 音频会话已停用事件。
 *
 * @since 12
 */
typedef struct OH_AudioSession_DeactivatedEvent {
    /**
     * @brief 音频会话停用原因。
     */
    OH_AudioSession_DeactivatedReason reason;
} OH_AudioSession_DeactivatedEvent;

/**
 * @brief 音频会话状态变更事件。
 *
 * @since 20
 */
typedef struct OH_AudioSession_StateChangedEvent {
    /**
     * @brief 音频会话停用的具体原因。
     */
    OH_AudioSession_StateChangeHint stateChangeHint;
} OH_AudioSession_StateChangedEvent;

/**
 * @brief 这个函数指针将指向用于监听音频会话状态变更事件的回调函数。
 *
 * @param event 指向{@link OH_AudioSession_StateChangedEvent}音频会话状态变更事件。
 * @since 20
 */
typedef void (*OH_AudioSession_StateChangedCallback) (
    OH_AudioSession_StateChangedEvent event);

/**
 * @brief 此函数指针将指向用于返回变化的音频设备描述符的回调函数，可能会返回多个音频设备描述符。
 *
 * @param type 设备连接状态类型，已连接或断开，指向OH_AudioDevice_ChangeType。
 * @param audioDeviceDescriptorArray 音频设备描述符数组，指向OH_AudioDeviceDescriptorArray。\n
 * 不再继续使用audioDeviceDescriptorArray指针时，请使用{@link OH_AudioSessionManager_ReleaseDevices}进行释放。
 * @since 21
 */
typedef void (*OH_AudioSession_AvailableDeviceChangedCallback) (
    OH_AudioDevice_ChangeType type,
    OH_AudioDeviceDescriptorArray *audioDeviceDescriptorArray);
 
/**
 * @brief 这个函数指针将指向用于监听当前输入设备变化事件的回调函数。
 *
 * @param devices 音频设备描述符数组，指向OH_AudioDeviceDescriptorArray。\n
 * 不再继续使用devices指针时，请使用{@link OH_AudioSessionManager_ReleaseDevices}进行释放。
 * @param changeReason 指向OH_AudioStream_DeviceChangeReason，设备变更原因。
 * @since 21
 */
typedef void (*OH_AudioSession_CurrentInputDeviceChangedCallback) (
    OH_AudioDeviceDescriptorArray *devices,
    OH_AudioStream_DeviceChangeReason changeReason);

/**
 * @brief 这个函数指针将指向用于监听当前输出设备变化事件的回调函数。
 *
 * @param devices 音频设备描述符数组，指向{@link OH_AudioDeviceDescriptorArray}设置音频设备描述符值的指针变量，
 * 不要单独释放audioDeviceDescriptorArray指针，而是调用{@link OH_AudioSessionManager_ReleaseDevices}来释放DeviceDescriptor数组。
 * @param changeReason 指向{@link OH_AudioStream_DeviceChangeReason}，用于接收设备变更原因。
 * @param recommendedAction 指向{@link OH_AudioSession_OutputDeviceChangeRecommendedAction}，用于接收设备变更后推荐的操作。
 * @since 20
 */
typedef void (*OH_AudioSession_CurrentOutputDeviceChangedCallback) (
    OH_AudioDeviceDescriptorArray *devices,
    OH_AudioStream_DeviceChangeReason changeReason,
    OH_AudioSession_OutputDeviceChangeRecommendedAction recommendedAction);

/**
 * @brief 这个函数指针将指向用于监听音频会话停用事件的回调函数。
 *
 * @param event 指向{@link #OH_AudioSession_Deactivated_Event}音频会话已停用事件。
 * @since 12
 */
typedef int32_t (*OH_AudioSession_DeactivatedCallback) (
    OH_AudioSession_DeactivatedEvent event);

/**
 * @brief 获取音频会话管理器。
 *
 * 使用音频会话管理器相关功能，首先需要获取音频会话管理器实例。
 *
 * @param audioSessionManager 指向OH_AudioSessionManager音频会话管理器实例。
 *
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统错误。
 * @since 12
 */
OH_AudioCommon_Result OH_AudioManager_GetAudioSessionManager(
    OH_AudioSessionManager **audioSessionManager);

/**
 * @brief 激活音频会话。
 *
 * @param audioSessionManager 指向{@link #OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param strategy 指向{@link #OH_AudioSession_Strategy}，用于设置音频会话策略。
 * @return 函数返回值：
 *         AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数strategy无效。\n
 *         AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE：非法状态。
 * @since 12
 */
OH_AudioCommon_Result OH_AudioSessionManager_ActivateAudioSession(
    OH_AudioSessionManager *audioSessionManager, const OH_AudioSession_Strategy *strategy);

/**
 * @brief 停用音频会话。
 *
 * @param audioSessionManager 指向{@link #OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：参数audioSessionManager为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE：非法状态。
 * @since 12
 */
OH_AudioCommon_Result OH_AudioSessionManager_DeactivateAudioSession(
    OH_AudioSessionManager *audioSessionManager);

/**
 * @brief 检查音频会话是否已激活。
 *
 * @param audioSessionManager 指向{@link #OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @return 用于返回当前应用的音频会话是否已激活，true表示已激活，false表示已停用。
 * @since 12
 */
bool OH_AudioSessionManager_IsAudioSessionActivated(
    OH_AudioSessionManager *audioSessionManager);

/**
 * @brief 注册音频会话停用事件回调。
 *
 * @param audioSessionManager 指向{@link #OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向OH_AudioSessionDeactivatedCallback，用于接收音频会话已停用事件。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。
 * @since 12
 */
OH_AudioCommon_Result OH_AudioSessionManager_RegisterSessionDeactivatedCallback(
    OH_AudioSessionManager *audioSessionManager, OH_AudioSession_DeactivatedCallback callback);

/**
 * @brief 取消注册音频会话停用事件回调。
 *
 * @param audioSessionManager 指向{@link #OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向OH_AudioSessionDeactivatedCallback，用于接收音频会话已停用事件。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。
 * @since 12
 */
OH_AudioCommon_Result OH_AudioSessionManager_UnregisterSessionDeactivatedCallback(
    OH_AudioSessionManager *audioSessionManager, OH_AudioSession_DeactivatedCallback callback);

/**
 * @brief 设置音频会话场景参数。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param scene 指向{@link OH_AudioSession_Scene}要设置的音频会话场景。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数scene为枚举范围外的值。\n
 *         AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE：系统当前状态下不允许设置，例如audio session未处于ready态。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 20
 */
OH_AudioCommon_Result OH_AudioSessionManager_SetScene(
    OH_AudioSessionManager *audioSessionManager, OH_AudioSession_Scene scene);

/**
 * @brief 注册音频会话状态变更事件回调。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向{@link OH_AudioSession_StateChangedCallback}，用于接收音频会话状态变更事件。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_NO_MEMORY：系统内存申请异常。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 20
 */
OH_AudioCommon_Result OH_AudioSessionManager_RegisterStateChangeCallback(
    OH_AudioSessionManager *audioSessionManager, OH_AudioSession_StateChangedCallback callback);

/**
 * @brief 取消音频会话状态变更事件回调。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向{@link OH_AudioSession_StateChangedCallback}，用于接收音频会话状态变更事件。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 20
 */
OH_AudioCommon_Result OH_AudioSessionManager_UnregisterStateChangeCallback(
    OH_AudioSessionManager *audioSessionManager, OH_AudioSession_StateChangedCallback callback);

/**
 * @brief 设置默认本机内置发声设备。
 *
 * 本接口适用范围如下：\n
 *
 * 当设置的{@link OH_AudioSession_Scene}为VoIP场景时，激活AudioSession后立即生效；
 * 如果{@link OH_AudioSession_Scene}为非VoIP场景，激活AudioSession时不会生效，
 * 直到启动播放的{@link OH_AudioStream_Usage}为语音消息、VoIP语音通话或VoIP视频通话时才生效。支持听筒、扬声器和系统默认设备。\n
 *
 * 本接口允许在{@link OH_AudioSessionManager}创建后随时调用。系统记录应用设置的默认本机内置发声设备，但只有激活AudioSession后才能生效。
 * 应用启动播放时，若外接设备如蓝牙耳机或有线耳机已接入，系统优先从外接设备发声；否则，系统遵循应用设置的默认本机内置发声设备。\n
 *
 * 本接口优先级低于{@link AVCastPicker}。如果使用AVCastPicker切换过发声设备，再次调用本接口切换设备将不生效。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param deviceType 指向{@link OH_AudioDevice_Type}用于设置发声设备类型。可设置的设备类型包括：\n
 *                                          AUDIO_DEVICE_TYPE_EARPIECE：听筒。\n
 *                                          AUDIO_DEVICE_TYPE_SPEAKER：扬声器。\n
 *                                          AUDIO_DEVICE_TYPE_DEFAULT：系统默认设备。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数deviceType超出枚举OH_AudioDevice_Type范围。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 20
 */
OH_AudioCommon_Result OH_AudioSessionManager_SetDefaultOutputDevice(
    OH_AudioSessionManager *audioSessionManager, OH_AudioDevice_Type deviceType);

/**
 * @brief 获取通过{@link OH_AudioSessionManager_SetDefaultOutputDevice}设置的默认发声设备。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param deviceType 指向{@link OH_AudioDevice_Type}用于获取发声设备类型参数指针。返回的设备类型包括：\n
 *                                          AUDIO_DEVICE_TYPE_EARPIECE：听筒。\n
 *                                          AUDIO_DEVICE_TYPE_SPEAKER：扬声器。\n
 *                                          AUDIO_DEVICE_TYPE_DEFAULT：系统默认设备。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数deviceType为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE：系统当前状态下不允许获取默认设备类型，例如audio session未处于ready态。
 * @since 20
 */
OH_AudioCommon_Result OH_AudioSessionManager_GetDefaultOutputDevice(
    OH_AudioSessionManager *audioSessionManager, OH_AudioDevice_Type *deviceType);

/**
 * @brief 释放音频设备描述符数组对象。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param audioDeviceDescriptorArray  需要释放的音频设备描述符数组。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数audioDeviceDescriptorArray为nullptr。
 * @since 20
 */
OH_AudioCommon_Result OH_AudioSessionManager_ReleaseDevices(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioDeviceDescriptorArray *audioDeviceDescriptorArray);

/**
 * @brief 注册当前输出设备变化回调。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向{@link OH_AudioSession_CurrentOutputDeviceChangedCallback}，用于返回音频设备变更信息的回调函数。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_NO_MEMORY：系统内存申请异常。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 20
 */
OH_AudioCommon_Result OH_AudioSessionManager_RegisterCurrentOutputDeviceChangeCallback(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioSession_CurrentOutputDeviceChangedCallback callback);

/**
 * @brief 取消注册当前输出设备变化回调。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向{@link OH_AudioSession_CurrentOutputDeviceChangedCallback}，用于返回音频设备变更信息的回调函数。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 20
 */
OH_AudioCommon_Result OH_AudioSessionManager_UnregisterCurrentOutputDeviceChangeCallback(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioSession_CurrentOutputDeviceChangedCallback callback);

/**
 * @brief 获取音频可选设备列表。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param deviceUsage 指向OH_AudioDevice_Usage用于设置要获取的设备种类。
 * @param audioDeviceDescriptorArray 音频设备描述符数组，指向OH_AudioDeviceDescriptorArray。\n
 * 不再继续使用audioDeviceDescriptorArray指针时，请使用{@link OH_AudioSessionManager_ReleaseDevices}进行释放。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1.参数audioSessionManager为nullptr；\n
 *                                                        2.参数deviceUsage无效;\n
 *                                                        3.参数audioDeviceDescriptorArray为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_GetAvailableDevices(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioDevice_Usage deviceUsage, OH_AudioDeviceDescriptorArray **audioDeviceDescriptorArray);

/**
 * @brief 注册可用设备更改回调。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param deviceUsage 指向OH_AudioDevice_Usage用于设置要获取的设备种类。
 * @param callback 指向OH_AudioSession_AvailableDeviceChangedCallback，用于返回可用音频设备变更信息的回调函数。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数deviceUsage无效；\n
 *                                                        3. 参数callback为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_RegisterAvailableDevicesChangeCallback(
    OH_AudioSessionManager *audioSessionManager, OH_AudioDevice_Usage deviceUsage,
    OH_AudioSession_AvailableDeviceChangedCallback callback);

/**
 * @brief 取消注册可用设备更改回调。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向OH_AudioSession_AvailableDeviceChangedCallback，用于返回可用音频设备变更信息的回调函数。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_UnregisterAvailableDevicesChangeCallback(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioSession_AvailableDeviceChangedCallback callback);

/**
 * @brief 设置媒体输入设备。
 *
 * 此功能不适用于呼叫录音，即SourceType为SOURCE_TYPE_VOICE_CALL或者SOURCE_TYPE_VOICE_COMMUNICATION的场景不适用。\n
 * 在存在更高优先级的并发录音流的场景中，应用程序实际使用的输入设备可能与所选设备不同。\n
 * 应用程序可以使用OH_AudioSessionManager_RegisterCurrentInputDeviceChangeCallback
 * 注册一个回调来监听实际的输入设备。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param deviceDescriptor 目标设备。可用设备必须位于由OH_AudioSessionManager_GetAvailableDevices返回的数组中。\n
 * 当传递nullptr时，系统将清除上一次的设置。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：参数audioSessionManager为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_SelectMediaInputDevice(
    OH_AudioSessionManager *audioSessionManager, OH_AudioDeviceDescriptor *deviceDescriptor);

/**
 * @brief 获得通过OH_AudioSessionManager_SelectMediaInputDevice设置的媒体输入设备。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param audioDeviceDescriptor 通过OH_AudioSessionManager_SelectMediaInputDevice设置的媒体设备，
 * 如果没有设置，返回一个类型为AUDIO_DEVICE_TYPE_INVALID的设备。\n
 * 不再继续使用audioDeviceDescriptor指针时，请使用{@link OH_AudioSessionManager_ReleaseDevice}进行释放。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数audioDeviceDescriptor为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_GetSelectedMediaInputDevice(
    OH_AudioSessionManager *audioSessionManager, OH_AudioDeviceDescriptor **audioDeviceDescriptor);

/**
 * @brief 设置在使用蓝牙或星闪进行录音时，应用程序的设备偏好分类。
 *
 * 应用程序可以在蓝牙或星闪连接之前设置此分类，系统将在设备连接时优先使用蓝牙或星闪进行录音。\n
 * 在更高优先级的并发录音流的场景中，应用程序实际使用的输入设备可能与当前设置的偏好设备不同。\n
 * 应用程序可以使用OH_AudioSessionManager_RegisterCurrentInputDeviceChangeCallback
 * 注册一个回调来监听实际的输入设备。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param category 指向OH_AudioSession_BluetoothAndNearlinkPreferredRecordCategory，
 * 在使用蓝牙或星闪进行录音时，应用程序的设备偏好分类。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数category错误。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_SetBluetoothAndNearlinkPreferredRecordCategory(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioSession_BluetoothAndNearlinkPreferredRecordCategory category);

/**
 * @brief 获取应用程序设置的在使用蓝牙或星闪进行录音时的设备偏好分类。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param category 指向OH_AudioSession_BluetoothAndNearlinkPreferredRecordCategory，
 * 在使用蓝牙或星闪进行录音时，应用程序的设备偏好分类。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数category为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_GetBluetoothAndNearlinkPreferredRecordCategory(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioSession_BluetoothAndNearlinkPreferredRecordCategory *category);

/**
 * @brief 注册音频会话管理器的输入设备更改回调。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向OH_AudioSession_CurrentInputDeviceChangedCallback，用于返回音频输入设备变更信息的回调函数。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_NO_MEMORY：内存不足。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_RegisterCurrentInputDeviceChangeCallback(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioSession_CurrentInputDeviceChangedCallback callback);
 
/**
 * @brief 取消注册音频会话管理器的输入设备更改回调。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param callback 指向OH_AudioSession_CurrentInputDeviceChangedCallback，用于返回音频输入设备变更信息的回调函数。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数callback为nullptr。\n
 *         AUDIOCOMMON_RESULT_ERROR_SYSTEM：系统异常，例如系统服务异常退出等。
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_UnregisterCurrentInputDeviceChangeCallback(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioSession_CurrentInputDeviceChangedCallback callback);
 
/**
 * @brief 释放音频设备描述符对象。
 *
 * @param audioSessionManager 指向{@link OH_AudioManager_GetAudioSessionManager}创建的音频会话管理实例。
 * @param audioDeviceDescriptor 需要被释放的音频设备描述符对象。
 * @return AUDIOCOMMON_RESULT_SUCCESS：函数执行成功。\n
 *         AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM：\n
 *                                                        1. 参数audioSessionManager为nullptr；\n
 *                                                        2. 参数audioDeviceDescriptor为nullptr。\n
 * @since 21
 */
OH_AudioCommon_Result OH_AudioSessionManager_ReleaseDevice(
    OH_AudioSessionManager *audioSessionManager,
    OH_AudioDeviceDescriptor *audioDeviceDescriptor);
#ifdef __cplusplus
}
#endif

#endif // NATIVE_AUDIO_SESSION_MANAGER_H
/** @} */